/**
 * RetryOnExceptionHandler.java
 * 
 * Created on Jun 4, 2008 at 8:42:25 PM
 */
package org.lego4j;

/**
 * Instances of this class represent a set of predefined exception handling policies.
 * 
 * Users of this policy must invove {@link #isExceptionRecoverable(Throwable)} first to find out if thrown exception
 * is recoverable, and subsequently invoke {@link #nextDelay(long, int)} to find out how long to wait for before 
 * retrying.
 *
 * @author <a href="alexguev@gmail.com">Alexei Guevara</>
 * @version $Revision:$ updated on $Date:$ by $Author:$
 */
public interface IRetryOnExceptionPolicy {

    /**
     * @param theE The exception thrown.
     * @return <b>true</b> if we should retry the execution of the method that threw the exception, 
     *         <b>false</b> otherwise. 
     */
    public boolean isExceptionRecoverable( Throwable theE );

    /**
     * called after {@link #isExceptionRecoverable(Throwable)} return true.
     * 
     * @param theStartTime The time when the method execution was first attempted.
     * @param theNumPreviousRetries The number of previous retries. 
     * @return next delay in milliseconds, or negative if no more retries.
     */
    public long nextDelay( long theStartTime, int theNumOreviousRetries );
    
}
